Writing dynamic and reproducible documents

An introduction to R Markdown / Quarto

Author
Affiliation

Julien Martin

BIO 8940 - Lecture 2

Published

February 15, 2024

Credit: Ignasi Bartomeus, PhD

0.1

1 How can you reproduce results?

1.1

1.2 What do we need to make research reproducible?

  • Something to integrate text, figures and code
    • R, Python, etc
  • Something that can be continuously edited and updated
    • Living or dynamic document
  • Something that can be easily used in versioning tools
    • Git

1.3

1.4 Quarto ?

  • multi-language, next generation version of R Markdown

  • include many new new features and capabilities

  • Like R Markdown, Quarto uses knitr to execute R code, and is therefore able to render most existing Rmd files without modification.

1.5 R Markdown workflow

1.6 Quarto workflow

2 Structure of a Rmd/qmd document

2.1

qmd/Rmd
YAML frontmatter
Markdown content
Code chunks

2.2 Rmd/qmd document

2.3 Rmd/qmd document

3 Markdown
qmd/Rmd
YAML frontmatter
Markdown content
Code chunks

3.1 What is Markdown?

  • A way to write stuff
  • Mostly plain words, with some formating

3.2 Websites that use Markdown

3.3 Headers

  • Use # to create headers
  • Multiple #’s create lower level headers

3.4 Text

  • Text is rendered as plain text

3.5 Lists

  • Use asterisks to make bullet points
  • Use numbers to make numbered lists
  • Use 4 spaces or 1 tab for indentation

3.7 Images

  • Use a link preceded by an ! to insert an image
  • The link text should be
    • a URL if the image is hosted online
    • a file path if the image is saved on your computer

3.8 Equations

  • Write equations with Latex syntax

3.9 Equation blocks

3.10 Tables

| header A | header B  | header C |
|:---------:|:--------:|---------:|
| left      | center   | right    |

Table: This is a title
This is a title
header A header B header C
left center right

3.11 R Markdown Reference Guide

https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf

4 Knitr Code chunks
qmd/Rmd
YAML frontmatter
Markdown content
Code chunks

4.1 Embed code

  • Insert chunk of R code
  • Code will run and include results.

4.2 Inline code

  • Place code in a sentence with
  • Code will be replaced with results

4.3 Chunk options

Rmd (R markdown) and qmd (quarto) differ:

  • Rmd: chunk options on one line between the {} after the r
  • qmd: either as Rmd or within the chunk with yaml style notation

Rmd

```{r name, echo=FALSE}
1+1
```

Can lead to really long lines

qmd

```{r}
#| label: name
#| echo: false
1+1
```

takes more vertical space but cleaner

4.4 echo

  • echo = FALSE or #| echo: false hides code.

4.5 eval

  • eval = FALSE or #| eval: false prevents code from being run
  • No results is displayed, only code

4.6 fig.height, fig.width

  • Specify dimension of plots (in inches) with fig.width and fig.height
  • Separate multiple arguments with commas.

4.7 message

  • message = FALSE or #| meassage: falseprevents messages from appearing in output

4.8 Default chunk options

  • Repeating chunk options can be painful

  • If you have echo = FALSE in every single chunk, how to set the default chunk option to echo = FALSE ?

  • Use knitr::opts_chunk$set(echo = FALSE)

  • You may overwrite the default for each chunk

  • For chunk options, check out https://yihui.name/knitr/options/

4.9 Including tables

# cars is a built-in-to-R data set of cars and their stopping distances
cars %>%
  head(4) %>%
  knitr::kable(format = "html", caption = "A kable table")
A kable table
speed dist
4 2
4 10
7 4
7 22
  • The kable package is often used with the kableExtra package
  • A number of other packages are available for making pretty tables, by far my favourite is gt using similar approach to table that ggplot has to figures

4.10 R Markdown Reference Guide

https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf

5 YAML: Yet Another Markup Language
qmd/Rmd
YAML frontmatter
Markdown content
Code chunks

5.1 YAML in brief

  • Contains the metadata of the document

  • Starts and ends by three dashes

  • Comes first in the document

5.2 Simplest example

5.3 Knit

5.4 Output formats

5.5 Appearance and style

Rmd

  • In HTML output, you can use theme or a custom .css style sheet

  • theme options (bootswatch.com) : “cerulean”, “journal”, “flatly”, “darkly”, “readable”, “spacelab”, “united”, “cosmo”, “lumen”, “paper”, “sandstone”, “simplex”, “yeti”

  • You may also use LaTeX templates with R Markdown, and write reproducible scientific paper

qmd

  • this is were Quarto is leaps beyong R markdown

  • excellent doc on the website

6 Managing bibliography

6.1 Reference file

  1. Put references in a plain text file with the extension .bib, in BibTex format (my advice: use Zotero and betterbibtex extension for dynamic file)
*@article{Shea2014,
  author =        {Shea, Nicholas and Boldt, Annika},
  journal =       {Trends in Cognitive Sciences},
  pages =         {186--193},
  title =         {{Supra-personal cognitive control}},
  volume =        {18},
  year =          {2014},
  doi =           {10.1016/j.tics.2014.01.006},
}
  1. Reference this file in your YAML header and add a csl style for formatting (browse through and download styles at zotero.org/styles)
---
title: "Citation test"
output: html_document
bibliography: example.bib
csl: my-style.csl 
---

6.2 Citations

  1. In your text, citations go inside brackets and separated by semicolons

This…

Blah blah [@Shea2014; @Lottridge2012].

turns into this…

Blah blah (Shea et al. 2014; Lottridge et al. 2012).

6.3 Citations

  1. In your text, citations go inside brackets and separated by semicolons

This…

Blah blah [@Shea2014; @Lottridge2012].

@Shea2014 says blah.

Blah blah [see @Shea2014, pp. 33-35; also @Wu2016, ch. 1].

turns into this…

Blah blah (Shea et al. 2014; Lottridge et al. 2012).

Shea et al. (2014) says blah.

Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1).

6.4 Citations

For an easy way to insert citations, try the citr RStudio add-in.

If you are using Zotero, then RStudio can link directly for both Rmd and qmd files (same for VScode)

7 Notebook vs console in Rstudio

7.1 Notebook and console

In Rstudio, Rmarkdown file = notebook

Meaning that R output:

  • are embedded in doc
  • not available in R envir and console

If you don’t like the notebook and want the console, add to YAML header

editor_options:
  chunk_output_type: console

7.2 Notebook

7.3 Console

7.4 R Markdown Reference Guide

https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf

8 What else can we do with R Markdown/ Quarto?

8.1 Let’s have a tour

8.2 To go further

Most of what works for R markdown works for Quarto

R Markdown cookbook


R Markdown Guide


Quarto website

9 Happy coding

I borrowed slides from Garrett Grolemund, Ulrik Lyngs, Olivier Gimenez . I also used the beautiful illustrations shared by Allison Horst